Conflict resolution
A conflict occurs when two systems hold different versions of the same data record, and both versions were modified after the last synchronization. This page explains what constitutes a conflict, the conditions that produce one, and the resolution strategies an integrator can implement. Sync frequency -- how often to poll and how that affects the conflict window -- is covered in sync frequency.
What a conflict is
A conflict is a specific condition: two systems hold a different version of the same record, and both versions changed after the last successful synchronization. The integrator's conflict detection logic must identify this state before deciding which version to apply.
A conflict is not the same as an error. An error is a failed request -- a network timeout,
a 422 Unprocessable Entity response, a transient service disruption. Errors are handled
by retry logic; they do not require a decision about which data version is correct. For
guidance on handling failed requests, see error handling.
A conflict is also not the same as a sync gap. A sync gap is a record that exists in one system but has not yet been transferred to the other -- it is absent, not contradictory. Sync gaps are resolved by transferring the missing record. Conflicts arise when the record is present in both systems but the two copies diverge.
The distinction matters because the three conditions require different responses. An error needs a retry. A sync gap needs a transfer. A conflict needs a decision: which version is authoritative, or how to merge them.
This responsibility is most acute in bi-directional integrations, where both systems can write to the same data types. In a strictly integrated system to Qoyod or Qoyod to integrated system integration, the source-of-truth system's version always takes precedence and conflicts cannot arise by definition.
When conflicts occur
Conflicts require two conditions to be true simultaneously: both systems must have written to the same record, and a synchronization must not have occurred between those two writes.
Concurrent edits are the most direct cause. If a product's price is updated in Qoyod at 10:00 and updated in the integrated system at 10:02, and the integration polls at 10:05, both systems present a changed price. Neither write is wrong in isolation -- but they cannot both be applied without choosing one.
Delayed polling widens the window during which a conflict can form. A longer gap between polls means more time for both systems to accumulate independent changes. Reducing poll frequency does not cause conflicts, but it increases the number of records that may be in a conflicted state when the poll runs. See sync frequency for polling cadence guidance.
Manual edits in Qoyod alongside automated writes from the integration are a common conflict source in practice. An integration may write product data to Qoyod automatically, while a Qoyod user manually adjusts a quantity or price in the Qoyod interface. If the integration then writes an updated value without first checking Qoyod's current state, it will overwrite the manual edit.
Network failures during synchronization can produce partial sync states. If a sync run transfers some records and then fails mid-run, the next run may encounter records where one system reflects the mid-run state and the other reflects a subsequent change. Maintaining a reliable cursor or timestamp per record limits the blast radius of partial failures.
Resolution strategies
The integrator chooses a resolution strategy based on which data types the integration handles and which system owns each type. No single strategy fits every integration; many integrations use different strategies for different fields or record types.
| Strategy | When to use | Integrator implements | Trade-off |
|---|---|---|---|
| Last-write-wins | Most recent change is always correct regardless of source | Compares timestamps from both systems; | |
| applies the record with the later timestamp | Simple. Risk of overwriting intentional manual edits if clocks are unsynchronized | ||
| Source-of-truth designation | One system owns a data type entirely | Applies the owning system's version without | |
| comparison, per field or record type | Eliminates conflicts for designated types. Requires deliberate ownership decisions | ||
| upfront | |||
| Merge | Both systems make valid changes to different fields of the same record | Reads both records field by field; | |
| applies each system's changes to the fields it modified | Preserves both changes when non-overlapping. Complex; requires | ||
| per-field change tracking | |||
| Manual review queue | High-value data where an automated decision carries unacceptable risk | Flags conflicted records; | |
| pauses sync until a human resolves; applies the human's decision | Guarantees accuracy for critical records. Introduces latency; | ||
| requires operational tooling |
In practice, most integrations combine strategies: source-of-truth designation for data types with a clear owner, last-write-wins for low-stakes fields, and manual review for pricing or financial quantities. The choice is an integration design decision, not an API constraint.
Once a resolution strategy produces a canonical version of the record, the integrator writes it back to the non-authoritative system. Tracking the outcome supports audit and debugging. This tracking is part of sync reconciliation: the broader process of bringing the two systems back into alignment after a conflict has been detected and resolved.
The term "sync reconciliation" refers to resolving data discrepancies between Qoyod and an integrated system. This is distinct from bank reconciliation, which is an accounting operation comparing bank statements to ledger entries. The two are unrelated; this page covers only sync reconciliation.